What is an R package and when should I make one?

This question is key!

Let’s start with our toy example

This is an specific example of your everyday process

• The code below is counting how many cars in mtcars (composed of 32 observations) have 4, 6, and 8 cylinders

library(tidyverse, quietly = TRUE)

mtcars |>
  group_by(cyl) |>
  summarize(count = n()) |>
  rename("class" = cyl)

# A tibble: 3 × 2
  class count
  <dbl> <int>
1     4    11
2     6     7
3     8    14

Is an R package the answer to our previous automation and sharing inquiries?

Yes, it is!

How are R packages shared and downloaded?

• We have the Comprehensive R Archive Network (CRAN)

What will be our learning goals?

Hands-on building an R package

Before proceeding…

Attribution: This content has been developed on the basis provided by Chapter 1: The Whole Game (R packages book by Hadley Wickham & Jenny Bryan, 2e) and the UBC course notes Reproducible and Trustworthy Workflows for Data Science by Tiffany Timbers, Joel Östblom, Florencia D’Andrea, and Rodolfo Lourenzutti

We need to register a GitHub account and install git (more information here)

Toy package: {eda}

Installing auxiliary R packages

Installation and loading code

• Installing {devtools} automatically installs {usethis}
• Same situation applies when it come to loading the packages

install.packages("devtools")

library(devtools)

Function create_package()

Code

create_package("~/Desktop/eda")

Project layout description (ignore-type files)

Project layout description (other components)

Function use_git()

library(devtools)

use_git()

What does this function specifically do?

• It creates hidden .git directory in the folder {eda}
• Furthermore, it creates your initial commit

Ensuring we made our initial commit

• Let’s relaunch our RStudio project eda.Rproj
• On the Git tab, click on the clock icon to check your commit history (note your GitHub user is shown in the Author column)

Write your first function!

mtcars |>
  group_by(cyl) |>
  summarize(count = n()) |>
  rename("class" = cyl)

# A tibble: 3 × 2
  class count
  <dbl> <int>
1     4    11
2     6     7
3     8    14

This is our function count_classes()

count_classes <- function(data_frame, class_col) {
  if (!is.data.frame(data_frame)) {
    stop("`data_frame` should be a data frame or data frame extension (e.g. a tibble)")
  }

  data_frame |>
    dplyr::group_by({{ class_col }}) |>
    dplyr::summarize(count = dplyr::n()) |>
    dplyr::rename("class" = {{ class_col }})
}

Function use_r()

library(devtools)

use_r("count_classes")

How does it look on R Studio?

Local commit of changes

Then…

Commit confirmation

• We will get the below message once we have locally committed our changes

Function load_all()

• The next step in our package building process is to test informally our function count_classes()
• Function load_all() from {devtools} makes function count_classes() available for experimentation

load_all()

Then, we test our function

• We use data frame mtcars and column cyl
• The above variables correspond to function arguments data_frame and class_col, respectively

count_classes(data_frame = mtcars, class_col = cyl)

Setting up our remote GitHub repo

• Via our GitHub account, we will create a remote {eda} public repo (we will add the README.md file later)

Pushing our local commits to the remote repo

This is how our remote repo should look like:

And these are our two initial commits in the remote repo:

Function check()

• To ensure that our package is in full working order, we’d need to execute R CMD check in the shell (i.e., terminal)
• We use function check() from {devtools} via the R Console

check()

Heads-up!

Edit DESCRIPTION

Package: eda
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R: 
    person("First", "Last", , "first.last@example.com", role = c("aut", "cre"),
           comment = c(ORCID = "YOUR-ORCID-ID"))
Description: What the package does (one paragraph).
License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
    license
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.1

Let’s proceed with the edits!

• We will update the fields Title, Authors@R, and Description
• If you don’t have an ORCID, you can delete comment = c(ORCID = "YOUR-ORCID-ID")

Package: eda
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R: 
    person("G. Alexi", "Rodriguez-Arelis", , "alexrod@stat.ubc.ca", role = c("aut", "cre"))
Description: Provide data wrangling and summary functions to conduct a proper 
    exploratory data analysis.
License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
    license
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.1

Saving, committing, and pushing

• Once we have edited the DESCRIPTION file, we need to save our changes
• Then, as we did with the count_classes() function, let’s locally commit these changes (use the commit message Edit DESCRIPTION)
• Moving forward, within the Git tab in RStudio, we will remotely push our edits to our public repo on GitHub by clicking on the Push button

Ensuring we have remotely pushed our edits

• Firstly, within RStudio, you will get the below confirmation

• Then, we will be able to see our third commit in our remote repo

Function use_mit_license()

• To address one of the warnings obtained in the output of check(), we need to include a LICENSE.md
• Hence, we can use function use_mit_license() from {usethis} via the R Console

use_mit_license()

How does LICENSE.md look like?

Note: More about license matters later on in this workshop

Let’s take a look at the DESCRIPTION file!

• The License field gets updated as follows:

Package: eda
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R: 
    person("G. Alexi", "Rodriguez-Arelis", , "alexrod@stat.ubc.ca", role = c("aut", "cre"))
Description: Provide data wrangling and summary functions to conduct a proper 
    exploratory data analysis.
License: MIT + file LICENSE
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.1

Function document()

• Let’s document our count_classes() function via package {roxygen2}

• In RStudio, let’s open R/count_classes.R in the source editor

Using {roxygen2}

• Do Code > Insert roxygen skeleton
• We will get a documentation template we have to fill out

Filling out the template

• Let’s copy and paste the below documentation on the previous template for count_classes()

#' Count class observations
#' Creates a new data frame with two columns, 
#' listing the classes present in the input data frame,
#' and the number of observations for each class.
#'
#' @param data_frame A data frame or data frame extension (e.g. a tibble).
#' @param class_col Unquoted column name of column containing class labels.
#'
#' @return A data frame with two columns. 
#'   The first column (named class) lists the classes from the input data frame.
#'   The second column (named count) lists the number of observations for each class from the input data frame.
#'   It will have one row for each class present in input data frame.
#' @export
#'
#' @examples
#' count_classes(mtcars, cyl)

Then…

• Save your changes in R/count_classes.R
• Commit and push these changes to the remote repo (use the commit message Add roxygen header to document count_classes())

Using document() from {devtools}

• Let’s run the document() function in the R Console

document()

• This function creates man/count_classes.Rd in {eda}, which is the help we get when typing ?count_classes in the R Console

Viewing the outputs from document()

Using check() again

• Since we already included LICENSE.md in {eda}, let’s use check() again in the R Console to ensure the license-related warning is gone

Function install()

• It’s time to install our package {eda}
• That said, instead of using install.packages() as with any package in the CRAN, we will use install() from {devtools}

install()
library(eda)
count_classes(mtcars, cyl)

Let’s do it in the R console

Function use_testthat()

use_testthat()

Let’s do it in the R console

• Commit and push these changes to the remote repo (use the commit message Add testing infrastructure)

Function use_test()

• This helper function from {usethis} creates a test file in tests/testthat/ per function

use_test("count_classes")

• In test-count-classes.R, you will see an example test which should be changed to an applicable one for count_classes() (more on testing later on in this workshop)

Let’s do it in the R console

• Commit and push these changes to the remote repo (use the commit message Test count_classes())

Function test()

• Suppose you have already built suitable test functions for your package
• The next step is running test() from {devtools}

test()

Let’s do it in the R console

• test() runs all our test functions and provides the corresponding testing results

Function use_package()

• Note that count_classes() uses functions from package {dplyr}

• Therefore, {dplyr} becomes a dependency

How to include a dependency in our package?

• We can use function use_package() from {usethis}

use_package("dplyr")

• This function will include {dplyr} in our DESCRIPTION, more specifically in Imports

Let’s do it in the R console

• Commit and push these changes to the remote repo (use the commit message Import dplyr)

Function use_readme_rmd()

• Our remote repo still doesn’t have a README.md file describing the package, installation, and usage
• We can automatically generate one via use_readme_rmd() from {usethis}

use_readme_rmd()

The .Rmd file

• Fill out the template, knit to .md, use build_readme(),commit, and push these changes to the remote repo (use the commit message Write README.Rmd and render)

Using check() and install()

• We’re done with the basic steps to build our R package
• Again, we use check() (to ensure all warnings are gone!), and then re-build via install()

Review

• We can review the previous process via the below diagram from Chapter 1: The Whole Game (R packages book by Hadley Wickham & Jenny Bryan, 2e)

Ensuring your code works as expected: an introduction to testing

• Software tests allow you to demonstrate to yourself and others, that your code works as expected.

• We all test our code informally, what we will talk about here is how to do this more formally so that our testing is reproducible and so we can automate the execution of our tests.

Formal software tests

To make this more concrete, here is an example of a formal software test for the count_classes function from our package:

What does this code do? It:

1. loads the package and testing library
2. simulates some simple and tractable test data
3. calls the count_classes function, providing the simple as input
4. reports that the count_classes function returns a tibble object as expected (and if it doesn’t work as expected, it prints out a useful message as to what went wrong)

Testability

Testability is defined as the degree to which a system or component facilitates the establishment of test objectives and the execution of tests to determine whether those objectives have been achieved.

In order to be successful, a test needs to be able to execute the code you wish to test, in a way that can trigger a defect that will propagate an incorrect result to a program point where it can be checked against the expected behaviour. From this we can derive four high-level properties required for effective test writing and execution. These are:

• controllability
• observability
• isolateablilty
• automatability

High-level properties for effective test writing and execution

controllability: the code under test needs to be able to be programmatically controlled

observability: the outcome of the code under test needs to be able to be verified

isolateablilty: the code under test needs to be able to be validated on its own

automatability: the tests should be able to be executed automatically

Source: CPSC 310 & CPSC 410 class notes from Reid Holmes, UBC]

What kinds of tests do we write for our functions?

When I am designing tests for my function, I like to think about three broad categories of tests, and then write 2-3 tests for each (or more if the function is complex and takes many arguments):

• Simple expected use cases

• Edge cases (unexpected, or rare use cases)

• Errors

We will come back to these and provide specific examples in a few minutes.

When do we write tests?

Anytime you think about writing a function!

Workflow for writing functions and tests

1. Write the function specifications and documentation - but do not implement the function.

2. Plan the test cases and document them.

3. Create test data that is useful for assessing whether your function works as expected.

4. Write the tests to evaluate your function based on the planned test cases and test data.

5. Implement the function by writing the needed code in the function body to pass the tests.

6. Iterate between steps 2-5 to improve the test coverage and function.

Example of workflow for writing functions and tests for data science

Let’s pretend we haven’t yet written our count_classes function, and follow the workflow I just outlined to develop our function and it’s test suite.

1. Write the function specifications and documentation - but do not implement the function

The first thing we should do is write the function specifications and documentation. This can effectively represented by an empty function and roxygen2-styled documentation in R as shown below:

2. Plan the test cases and document them

Next, we should plan out our test cases and start to document them.

At this point we can sketch out a skeleton for our test cases with code but we are not yet ready to write them, as we first will need to reproducibly create test data that is useful for assessing whether your function works as expected.

2. Plan the test cases and document them (cont’d)

So considering our function specifications, some kinds of input we might anticipate our function may receive, and correspondingly what it should return is listed in a table below:

TBD…

2. Plan the test cases and document them (cont’d)

Next, I sketch out a skeleton for the unit tests. For R, we will use the well maintained and popular testthat R package for writing our tests.

With testthat we create a test_that statement for each related group of tests for a function. For our example, we will create the four test_that statements shown below:

3. Create test data that is useful for assessing whether your function works as expected

Now that we have a plan, we can create reproducible test data for that plan! When we do this, we want to keep our data as small and tractable as possible. We want to test things we know the answer to, or can at a minimum calculate by hand. We will use R code to reproducibly create the test data. We will need to do this for the data we will feed in as inputs to our function in the tests, as well as the data we expect our function to return.

4. Write the tests to evaluate your function based on the planned test cases and test data

Now that we have the skeletons for our tests, and our reproducible test data, we can actually write the internals for our tests! We will do this by using expect_* functions from the testthat package. The table below shows some of the most commonly used expect_* functions. However, there are many more that can be found in the testthat expectations reference documentation.

testthat test structure:

4. Write the tests to evaluate your function based on the planned test cases and test data (cont’d)

Wait what??? Most of our tests fail…

Yes, we expect that, we haven’t written our function body yet!

5. Implement the function by writing the needed code in the function body to pass the tests

FINALLY!! We can write the function body for our function! And then call our tests to see if they pass!

6. Iterate between steps 2-5 to improve the test coverage and function

Are we done? For the purposes of this demo, yes! However in practice you would usually cycle through steps 2-5 two-three more times to further improve our tests and and function

Where do the function and test files go?

In the workflow above, we skipped over where we should put our tests and how to call them in an automated way.

Let’s go to this version of the {eda} package and explore how to do this:

• TBD

Publishing your R package

Source: https://posit-conf-2023.github.io/pkg-dev/materials/slides.pdf

Level 1: Publishing on GitHub

• GitHub is where almost all R packages start out publishing, and continue publishing development versions between releases.

• For this to work, you need to push your package code to GitHub and provide users instructions like this to download, build and install your package:

# install.packages("devtools")
devtools::install_github("username/package")

Level 2: Publishing on CRAN

• CRAN (founded in 1997) stands for the “Comprehensive R Archive Network”.
• CRAN is a collection of sites which host identical copies of:
  • R distribution(s)
  • the contributed extensions (i.e., packages)
  • documentation for R
  • binaries (i.e., packages)

Source: Hornik, K (2012). The Comprehensive R Archive Network. Wiley interdisciplinary reviews. Computational statistics. 4(4): 394-398. doi:10.1002/wics.1212

What does it mean to be a CRAN package?

How to submit a package to CRAN

Source: Chapter 22: Releasing to Cran - R packages book by Hadley Wickham & Jenny Bryan

Notes on submitting to CRAN

• Your package must pass R CMD check with the current development version of R.

• It must work on at least two platforms (CRAN uses the following 4 platforms: Windows, Mac OS X, Linux and Solaris) - use GitHub Actions to ensure this before submitting to CRAN!

If you decide to submit a package to CRAN, follow the detailed instructions in Chapter 22: Releasing to Cran from the R packages book by Hadley Wickham & Jenny Bryan.

Copyright & Licenses (who owns the code?)

Full disclosure… I AM NOT A LAWYER!

Learning Objectives

Copyright Law

• In both the US and Canada, software code falls under copyright law

• Copyright protects only the language and words used to express ideas, concepts and themes, not the ideas, concepts or themes themselves.

Canadian Copyright Law

In Canada, the copyright owner is afforded the following rights:

• Economic rights:
  • the right to produce, reproduce, publish, translate, authorize & convert a work

Who has copyright ownership?

This is a complicated question, and the answer starts with it depends on the case…

Case I: You author the code for yourself

• You author the code and you are doing this for yourself (i.e., not for your employer, not for a client, etc).

• In such a case, you (the person who typed the code) automatically become the copyright owner.

• In both Canada and the USA, you do not need to need to affix the copyright symbol © to your work (some other countries do require this however).

• Although the copyright symbol © is not required, it is often used in copyrighted works to clearly identify that the code is protected by copyright.

In both Canada and the US, it is possible (and advisable) to register your copyright as evidence that a copyright exists and who the owner is.

Case II: You write the code in the course of employment

• In Canada, if you write code for work as an employee the copyright ownership is typically assigned to the employer.

Implications when you forgo copyright ownership

Licenses

• If you publicly share your creative work (i.e., software code), you should let others know if and how they can reuse it!

• This is done via the inclusion of a LICENSE or LICENSE.txt file in the base directory of the repository that clearly states under which license the content is being made available.

Licenses (cont’d)

• Unless you include a license that specifies otherwise, nobody else can copy, distribute, or modify your work without being at risk of take-downs, shake-downs, or litigation.

• Once the work has other contributors (each a copyright holder), “nobody” starts including you!

• A license solves this problem by granting rights to others (the licensees) that they would otherwise not have.

Choosing a License

Choosing a License (cont’d)

• In practice, a few licenses are by far the most popular.

• choosealicense.com will help you find a common license that suits your needs.

💡Tip: Choose a license that is in common use! This makes life easier for contributors and users, because they are more likely to already be familiar with the license and don’t have to wade through a bunch of jargon to decide if they’re ok with it.

Creative Commons

• But not all my creative Data Science work is code (e.g. visualizations, reports, presentations), so how do I license it?

• The Creative Commons licences were created for such works and they are now widely used in academia and the publishing industry.

https://chooser-beta.creativecommons.org/

Creative Commons (cont’d)

Source: “How to License Poster” by Creative Commons is licensed under CC BY 4.0

Creative Commons (cont’d)

Source: “How to License Poster” by Creative Commons is licensed under CC BY 4.0

Scenario 1

Imagine you’re a data scientist and you developed a tool that analyzes satellite imagery to track deforestation patterns. Your primary goal is to make this tool freely available to researchers and other conservationists to help monitor and combat deforestation, but you still want to retain the copyright to your tool.

Scenario 2

Imagine you’re a data scientist and you have compiled a data set of climate change projections from various scientific sources. In order to promote further analyses aimed at understanding and mitigating the effects of climate change, you want to share this data set with the research community.

References

• Who Owns The Code?

• Canadian Copyright Law - University of Alberta

• Do you actually own the IP generated by your Canadian employees?

• Ownership of Copyright - Canadian Copyright Act

• The Unreasonable Fear of Infection

• Frequently Asked Questions about the GNU Licenses